/**
 *  CloudEdit- Editor colaborativo peer-to-peer
 *  Author: Miguel Souto Bartolomé
 *  Web: http://code.google.com/p/cloudedit/
 *
 *  This program is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

package com.google.gwt.cloudedit.client;

import java.util.ArrayList;

import com.google.gwt.cloudedit.shared.DatosArchivo;
import com.google.gwt.cloudedit.shared.DatosListado;
import com.google.gwt.user.client.rpc.AsyncCallback;

/**
 * Lado cliente asíncrono del servicio RPC. Permite la realización de peticiones
 * al servicio RCP de manera que su asincronidad no sea un problema para la
 * aplicación JavaScript cliente.
 * 
 * @author Miguel Souto Bartolomé
 * @version 4.0 
 */
public interface LlamadaPastryAsync {
	
	/**
	 * Inicia la red Pastry de tabla Hash distribuida asociada y levanta los
	 * servicios de gestión de archivos y gestión de mensajes correspondientes.
	 * Estas operaciones solo se realizan al conectarse la primera sesión cliente.
	 *
	 * @param asyncCallback the async callback
	 * @throws IllegalArgumentException the illegal argument exception
	 */
	void inicia(AsyncCallback<Void> asyncCallback)
			throws IllegalArgumentException;
	
	/**
	 * Graba los cambios del archivo de datos que está siendo
	 * editado en la red distribuida.
	 *
	 * @param datos el archivo
	 * @param asyncCallback the async callback
	 * @throws IllegalArgumentException the illegal argument exception
	 */
	void graba(DatosArchivo datos, AsyncCallback<Void> asyncCallback)
	        throws IllegalArgumentException;
	
	/**
	 * Genera un identificador de archivo único y graba un nuevo archivo
	 * de datos codificado en XML en la red Pastry.
	 *
	 * @param file el nuevo archivo 
	 * @param nombreAnterior the nombre anterior
	 * @param asyncCallback the async callback
	 */
	void grabaComo(DatosArchivo file, String nombreAnterior, AsyncCallback<DatosArchivo> asyncCallback);
	
	/**
	 * Devuelve un archivo de la red Pastry
	 *
	 * @param id el identificador único del archivo que se desea abrir
	 * @param nombreAnterior el nombre del archivo que se estaba editando 
	 * @param asyncCallback the async callback
	 */
	void abre(String id, String nombreAnterior, AsyncCallback<DatosArchivo> asyncCallback);
	
	/**
	 * Envia una notificación al resto de nodos suscritos al mismo grupo
	 * para que actualicen su informacion sobre el mismo si están editando
	 * el mismo archivo.
	 *
	 * @param xml nnotificación codificada en XML
	 * @param file el archivo que el emisor está editando
	 * @param callback the callback
	 */
	void notifica(String xml, DatosArchivo file, AsyncCallback<Void> callback);
	
	/**
	 * Comprueba si algún otro nodo ha modificado la información del archivo
	 * que se está editando.
	 *
	 *
	 * @param callback the callback
	 */
	void comprueba(AsyncCallback<String> callback);
	
	/**
	 * Devuelve el listado de archivos presentes en la red Bunshin.
	 *
	 * @param asyncCallback the async callback
	 */
	void listado(AsyncCallback<ArrayList<DatosListado>> asyncCallback);
	
	/**
	 * Comprueba si un nombre de archivo ya existe en la red Bunshin.
	 *
	 * @param text el nombre de archivo
	 * @param asyncCallback the async callback
	 */
	void comprobarNombre(String text, AsyncCallback<String> asyncCallback);

	/**
	 * Graba el archivo en caso de no ser nuevo y cierra la conexión.
	 *
	 * @param datos nombre del archivo que se está editando
	 * @param modoEdicion el modo de edición
	 * @param callback the callback
	 */
	void cerrar(DatosArchivo datos, String modoEdicion, AsyncCallback<Void> callback);
	
	/**
	 * Comparar el contenido nuevo del fichero abierto con el antiguo almacenado
	 * por el editor, y nos devuelve el contendido nuevo con los cambios marcados.
	 *
	 * @param textoAntiguo el texto antiguo
	 * @param textoNuevo el texto nuevo
	 * @param asyncCallback the async callback
	 */
	void comparar(String textoAntiguo, String textoNuevo,
			AsyncCallback<String> asyncCallback);
	
	/**
	 * Método de apoyo a los casos de prueba para adecuar el contexto del Servlet y
	 * cerrar el nodo.
	 *
	 * @param operacion la operación
	 * @param callback the callback
	 */
	void resetContexto(String operacion, AsyncCallback<Void> callback);

}